feat: add harness engineering improvements by tudorpopams · Pull Request #35929 · microsoft/fluentui

tudorpopams · 2026-03-30T17:44:02Z

Summary

Implement harness engineering best practices for AI agent instructions in the Fluent UI repo.

Restructure agent instructions following progressive disclosure: AGENTS.md as a concise map, detailed docs in docs/
Add CLAUDE.md symlinked to AGENTS.md for cross-tool compatibility
Add agent skills for common development tasks under .agents/skills/ with thin .claude/skills/ wrappers
Improve ESLint rule error messages with doc URLs and fix instructions so AI agents can self-correct on failure
Fix all npx references to yarn across docs, skills, and copilot instructions to match the repo's package manager

What's included

Harness Engineering (docs/ restructure)

AGENTS.md slimmed to ~60 lines as a pointer-only map
.github/instructions/copilot.instructions.md reduced from 473 to ~50 lines
Detailed guidance moved to:
docs/architecture/component-patterns.md — v9 hooks, slots, Griffel
docs/architecture/design-tokens.md — token categories and usage
docs/architecture/layers.md — package dependency tiers
docs/workflows/contributing.md — PR checklist and commands
docs/workflows/testing.md — test types and SSR safety
docs/team-routing.md — teams, labels, CODEOWNERS
docs/quality-grades.md — per-package quality tracking
docs/tech-debt-tracker.md — known debt items for agents

Agent Skills (`.agents/skills/` + `.claude/skills/`)

Skills live in .agents/skills/ (tool-agnostic source of truth). Claude Code wrappers in .claude/skills/ reference them via @ relative path — no
symlinks, Windows-compatible.

Skill	Command	Purpose
`v9-component`	`/v9-component Name`	Scaffold a new v9 component with all required files
`change`	`/change`	Create beachball change file from current diff
`lint-check`	`/lint-check [pkg]`	Run lint, parse errors, and auto-fix common issues
`token-lookup`	`/token-lookup val`	Find the design token for a hardcoded CSS value
`package-info`	`/package-info pkg`	Quick package lookup: path, deps, owner, tests
`visual-test`	`/visual-test Name`	Visually verify a component via Storybook + playwright-cli
`review-pr`	`/review-pr #123`	Review a PR with confidence scoring and category checks

ESLint Error Message Improvements

Updated 5 existing rules (ban-context-export, ban-instanceof-html-element, no-global-react, no-restricted-imports, no-context-default-value) to
include fix instructions and docs/ references in error messages.

npx → yarn

All command references in docs, skills, and copilot instructions updated from npx to yarn to match the repo's package manager.

Test plan

Verify ESLint rules produce updated error messages with doc URLs
Verify CLAUDE.md symlink resolves correctly to AGENTS.md
Verify skills are available via / menu in Claude Code
Test /package-info react-button returns correct package details
Test /token-lookup #0078d4 suggests the right design token
Test /visual-test Button launches Storybook and captures a screenshot
Test /review-pr produces structured output with confidence score
Review docs for accuracy against current v9 patterns

github-actions · 2026-03-30T18:09:17Z

📊 Bundle size report

✅ No changes found

github-actions · 2026-03-30T18:21:54Z

Pull request demo site: URL

BreckoD

After resolving previous comments, it should be gtg. It's interesting whether the agents will be able to track all docs and rules described, but there's only one way to figure it out =)

… skills Adds five agentic workflows (.md + compiled .lock.yml): - agent-triage: classifies, labels, and validates incoming issues - agent-fix: implements bug fixes and opens PRs (triggered by agent:fix label) - agent-review: devil's advocate review with confidence scoring for agent PRs - agent-docs-grooming: weekly documentation audit - agent-skills-improvement: weekly analysis of agent PRs to improve instructions Also includes gh-aw init scaffolding (agentic-workflows agent, .gitattributes). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Merges global agent context (from .github/copilot-instructions.md) into AGENTS.md alongside the existing Nx guidelines. CLAUDE.md is a symlink to AGENTS.md so both Claude Code and Copilot read the same instructions. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Applies progressive disclosure, mechanical enforcement, and feedback loop patterns from OpenAI's harness engineering approach. 1. Progressive disclosure: Slim down copilot.instructions.md (473→50 lines) and AGENTS.md into pointer-only maps. Detailed docs moved to docs/: - docs/architecture/component-patterns.md (v9 hooks, slots, Griffel) - docs/architecture/design-tokens.md (token categories and usage) - docs/architecture/layers.md (package dependency tiers) - docs/workflows/contributing.md (PR checklist, commands) - docs/workflows/testing.md (test types, SSR safety) - docs/team-routing.md (teams, labels, CODEOWNERS) 2. Agent-guiding error messages: Updated all custom ESLint rules to include doc URLs and fix instructions in error messages so agents self-correct. 3. New ESLint rule: @fluentui/no-hardcoded-style-values — flags hardcoded colors and spacing in .styles.ts files, requiring design tokens. 4. Structural validation: check-v9-structure.js validates that component packages follow the canonical file structure. 5. Layer boundary validation: check-layer-boundaries.js validates that component packages (Tier 3) don't depend on other component packages. 6. Quality tracking: docs/quality-grades.md and docs/tech-debt-tracker.md for agents and engineers to track package quality and debt. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Removes no-hardcoded-style-values ESLint rule, check-layer-boundaries.js, and check-v9-structure.js as requested. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Applies findings from "Increasing AI coding success to 99%" article: - Add "instructions are source of truth, not existing code" as first line - Add critical rules as negative constraints ("Never X") in always-loaded context - Add concrete v9 component code template to override training defaults - Add legacy anti-patterns section warning about v8 code agents will find - Add exploration guidance for the large monorepo - Reframe positive guidance as negative constraints for higher compliance Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Remove all GitHub Agentic Workflow files (.github/workflows/agent-*, .github/agents/, .github/aw/) and clean up related references in AGENTS.md, docs, .prettierignore, and .gitattributes. This PR now focuses solely on harness engineering improvements. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Add 5 slash command skills under .claude/skills/: - /v9-component — scaffold a new v9 component with all required files - /change — create beachball change files from current diff - /lint-check — run lint, parse errors, and auto-fix common issues - /token-lookup — map hardcoded CSS values to design tokens - /package-info — quick package lookup (path, deps, owner, tests) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Add 6 skills under .agents/skills/ with thin .claude/skills/ wrappers: - /v9-component — scaffold a new v9 component - /change — create beachball change files - /lint-check — run lint and auto-fix common issues - /token-lookup — map hardcoded CSS values to design tokens - /package-info — quick package lookup - /visual-test — visually verify components via Storybook + playwright-cli Replace all npx references with yarn across docs, skills, and copilot instructions to match the repo's package manager. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Add /review-pr skill that reviews PRs across 8 categories: change file, V9 patterns, dependency layers, SSR safety, testing, API surface, accessibility, and security/quality. Produces a structured report with a 0-100 confidence score and APPROVE/REQUEST_CHANGES/COMMENT recommendation. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

- v9-component: use react-component and react-library generators instead of manually creating files, add generators reference table - change: use `yarn change` (repo's beachball script) and `yarn check:change` for verification - package-info: add useful commands section with Nx executors Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

- Use `yarn nx run react-<component>:start` instead of stories package - Handle dynamic Storybook port instead of hardcoding 6006 - Fix story ID pattern to `components-<component>--<story>` - Use port-based cleanup instead of `kill %1` Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

@latest

@latest resolves to an unstable alpha version that doesn't exist on npm. 0.1.1 is the stable version that works with global install. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

mainframev · 2026-04-17T12:45:17Z

+
+1. **Never hardcode colors, spacing, or typography values.** Always use design tokens from `@fluentui/react-theme`. See [docs/architecture/design-tokens.md](docs/architecture/design-tokens.md).
+2. **Never use `React.FC`.** Always use `ForwardRefComponent` with `React.forwardRef`.
+3. **Never access `window`, `document`, or `navigator` without SSR guards.** Use `canUseDOM()` from `@fluentui/react-utilities`.


maybe we should mention the targetDocument somewhere here, we usually do not use window / document directly, only via targetDocument / targetDocument.defaultView:

const { targetDocument } = useFluent_unstable(); const targetWindow = targetDocument?.defaultView; ... targetWindow.innerWidth

mainframev · 2026-04-17T14:29:18Z

+1. **Identify changed packages** by running:
+
+   ```bash
+   git diff --name-only HEAD~1
+   ```


I think this step is redundant, because if we will run yarn change or yarn check:change it should already report packages that need change files

…/fluentui-css-variants  chore/headless-css-variants $+ +706 -16 ❯❯❯ y change check  v1.0.0  v22.18.0 yarn run v1.23.34 $ beachball change --no-commit check Checking for changes against "upstream/master" fetching latest from remotes "upstream/master" Found changes in the following packages: @fluentui/react-storybook-addon-export-to-sandbox fetching latest from remotes "upstream/master"

mainframev · 2026-04-17T14:36:46Z

+## Rules
+
+- Every published package change MUST have a change file
+- Do not create change files for unpublished packages (stories packages, internal tools)


Is there a scenario when agent can manually create the change file bypassing yarn change command? Beachball automatically excludes private packages, so I guess we do not need that rule

- Add targetDocument/useFluent_unstable guidance for SSR-safe DOM access - Remove redundant package identification step from change skill (beachball auto-detects affected packages) - Simplify change skill rules: always use yarn change, never create change files manually Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

github-actions bot added the CI label Mar 30, 2026

github-actions bot reviewed Mar 30, 2026

View reviewed changes

Comment thread .gitattributes

tudorpopams marked this pull request as ready for review April 7, 2026 15:21

tudorpopams requested review from a team as code owners April 7, 2026 15:21

tudorpopams force-pushed the feat/copilot-agents branch from b4ca5af to eefc38b Compare April 7, 2026 15:22

tudorpopams requested review from Hotell, dmytrokirpa and mainframev April 8, 2026 12:05

tudorpopams changed the title ~~feat: add Copilot agentic workflows and harness engineering improvements~~ feat: add harness engineering improvements Apr 8, 2026

tudorpopams force-pushed the feat/copilot-agents branch 3 times, most recently from 79776c7 to 3354ce6 Compare April 13, 2026 10:02

mainframev reviewed Apr 14, 2026

View reviewed changes

Comment thread .agents/skills/visual-test/SKILL.md Outdated

mainframev reviewed Apr 14, 2026

View reviewed changes

Comment thread .agents/skills/visual-test/SKILL.md

mainframev reviewed Apr 14, 2026

View reviewed changes

Comment thread .agents/skills/visual-test/SKILL.md Outdated

BreckoD approved these changes Apr 14, 2026

View reviewed changes

tudorpopams force-pushed the feat/copilot-agents branch from 3354ce6 to 1bf68b7 Compare April 14, 2026 15:01

tudorpopams requested review from a team, Jacqueline-ms and Mitch-At-Work as code owners April 14, 2026 15:01

microsoft-github-policy-service bot added Area: Website PR: API Modified labels Apr 14, 2026

tudorpopams force-pushed the feat/copilot-agents branch from 9de8418 to 8132a03 Compare April 14, 2026 15:09

github-actions bot removed the CI label Apr 14, 2026

tudorpopams and others added 19 commits April 17, 2026 12:27

chore: remove new lint rules and validation scripts

03e37b4

Removes no-hardcoded-style-values ESLint rule, check-layer-boundaries.js, and check-v9-structure.js as requested. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

style: fix Prettier formatting for all new and modified files

faaa0bb

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

chore: exclude generated .lock.yml files from Prettier formatting

d27323d

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

docs: reference CODEOWNERS as source of truth in team-routing.md

b4da37f

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

chore: rename "Devil's Advocate" to "FluentUI Review" everywhere

fabc1c3

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

style: fix Prettier formatting for AGENTS.md

b26125e

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

style: fix Prettier formatting for AGENTS.md and skill files

96e9bdf

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

add playwright-cli output to gitignore

2479b52

fix: pin playwright-cli to 0.1.1 in visual-test skill

e1529ef

@latest resolves to an unstable alpha version that doesn't exist on npm. 0.1.1 is the stable version that works with global install. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

tudorpopams force-pushed the feat/copilot-agents branch from 8c5be65 to e1529ef Compare April 17, 2026 10:28

BreckoD approved these changes Apr 17, 2026

View reviewed changes

paolo-aliprandi approved these changes Apr 17, 2026

View reviewed changes

mainframev reviewed Apr 17, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: add harness engineering improvements#35929

feat: add harness engineering improvements#35929
tudorpopams wants to merge 20 commits intomicrosoft:masterfrom
tudorpopams:feat/copilot-agents

tudorpopams commented Mar 30, 2026 •

edited

Loading

Uh oh!

github-actions bot commented Mar 30, 2026 •

edited

Loading

Uh oh!

github-actions bot commented Mar 30, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

BreckoD left a comment

Uh oh!

mainframev Apr 17, 2026

Uh oh!

mainframev Apr 17, 2026 •

edited

Loading

Uh oh!

mainframev Apr 17, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

tudorpopams commented Mar 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

What's included

Harness Engineering (docs/ restructure)

Agent Skills (.agents/skills/ + .claude/skills/)

ESLint Error Message Improvements

npx → yarn

Test plan

Uh oh!

github-actions bot commented Mar 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📊 Bundle size report

Uh oh!

github-actions bot commented Mar 30, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

BreckoD left a comment

Choose a reason for hiding this comment

Uh oh!

mainframev Apr 17, 2026

Choose a reason for hiding this comment

Uh oh!

mainframev Apr 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mainframev Apr 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

tudorpopams commented Mar 30, 2026 •

edited

Loading

Agent Skills (`.agents/skills/` + `.claude/skills/`)

github-actions bot commented Mar 30, 2026 •

edited

Loading

mainframev Apr 17, 2026 •

edited

Loading

mainframev Apr 17, 2026 •

edited

Loading